feat: srw #1586

sophia-bq · 2025-10-30T17:04:53Z

Summary

introduces the Simple Read/Write Splitting Plugin (srw)

Description

an alternative to the existing Read/Write Splitting Plugin that connects directly to specified read and write endpoints

Additional Reviewers

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

docs/using-the-jdbc-driver/CompatibilityCrossPlugins.md

docs/using-the-jdbc-driver/using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md

...les/AWSDriverExample/src/main/java/software/amazon/SimpleReadWriteSplittingMySQLExample.java

wrapper/src/main/java/software/amazon/jdbc/plugin/AuroraInitialConnectionStrategyPlugin.java

sergiyvamz · 2025-11-04T22:47:27Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+    this.pluginService = pluginService;
+    this.properties = properties;
+    this.writeEndpoint = writeEndpoint;
+    this.readEndpoint = SRW_READ_ENDPOINT.getString(properties);


Does it mean that SRW_READ_ENDPOINT is optional parameter?

I've updated it so that SRW_READ_ENDPOINT is required

sergiyvamz · 2025-11-04T22:53:17Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+  }
+
+  private boolean isWriteEndpoint(final @NonNull HostSpec hostSpec) {
+    return Objects.equals(hostSpec.getHost(), this.writeEndpoint);


We need to use getHostAndPort() and verify equalsIgnoreCase()

Are we expecting that the port is included in the endpoint?

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

wrapper/src/test/java/integration/container/tests/SimpleReadWriteSplittingTest.java

wrapper/src/main/java/software/amazon/jdbc/plugin/failover/FailoverConnectionPlugin.java

aaron-congo · 2025-11-14T20:21:38Z

docs/using-the-jdbc-driver/using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md

+properties.setProperty("srwReadEndpoint", "test-db.cluster-ro-XYZ.us-east-2.rds.amazonaws.com");
+```
+
+If you would like to use the Simple Read/Write Splitting Plugin without the failover plugin, make sure you have the `srw` plugin in the `wrapperPlugins` property, and that the failover plugin is not part of it.


I know we use a similar blurb to this for the docs for the RW plugin but I can't remember why we mentioned this for this specific combination of plugins. Should we consider removing it? It seems self-explanatory to me.

aaron-congo · 2025-11-14T20:24:02Z

docs/using-the-jdbc-driver/using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md

+|------------------------------|:-------:|:--------:|:----------------------------------------------------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------------|
+| `srwWriteEndpoint`           | String  |   Yes    | The endpoint to connect to when `setReadOnly(false)` is called.                                                                               | `null`        | `<cluster-name>.cluster-<XYZ>.<region>.rds.amazonaws.com`    |
+| `srwReadEndpoint`            | String  |   Yes    | The endpoint to connect to when `setReadOnly(true)` is called.                                                                                | `null`        | `<cluster-name>.cluster-ro-<XYZ>.<region>.rds.amazonaws.com` |
+| `verifyNewSrwConnections`    | Boolean |    No    | Enables role verification for new connections made by the Simple Read/Write Splitting Plugin.                                                 | `true`        | `true`, `false`                                              |


What is the difference between verifyNewSrwConnections and verifyOpenedConnectionType? It sounds like the first enables verification of both readers and writers when setReadOnly is called, but the second enables verification for only "writers" or only "readers"? If the first is set but the second is not, does it verify both?

Can we add "More details below" to the descriptions for the bottom 4 parameters?

aaron-congo · 2025-11-14T20:24:43Z

docs/using-the-jdbc-driver/using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md

+```
+
+## Simple Read/Write Splitting Plugin Parameters
+| Parameter                    |  Value  | Required | Description                                                                                                                                   | Default Value | Example Value                                                |


aaron-congo · 2025-11-14T20:33:50Z

docs/using-the-jdbc-driver/using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md

+
+The values of `srwConnectRetryTimeoutMs` and `srwConnectRetryIntervalMs` control the timing and aggressiveness of the plugin's retries.
+
+Additionally, to consistently ensure the role of connections made with the plugin, the plugin also provides role verification for the initial connection. When connecting with an RDS writer cluster or reader cluster endpoint, the plugin will retry the initial connection up to `srwConnectRetryTimeoutMs` until it has verified connection to the intended role of the endpoint.


Suggested change

Additionally, to consistently ensure the role of connections made with the plugin, the plugin also provides role verification for the initial connection. When connecting with an RDS writer cluster or reader cluster endpoint, the plugin will retry the initial connection up to `srwConnectRetryTimeoutMs` until it has verified connection to the intended role of the endpoint.

Additionally, to consistently ensure the role of connections made with the plugin, the plugin also provides role verification for the initial connection. When connecting with an RDS writer cluster or reader cluster endpoint, the plugin will retry the initial connection up to `srwConnectRetryTimeoutMs` until it has verified the intended role of the endpoint.

aaron-congo · 2025-11-14T20:45:40Z

docs/using-the-jdbc-driver/using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md

+
+Additionally, to consistently ensure the role of connections made with the plugin, the plugin also provides role verification for the initial connection. When connecting with an RDS writer cluster or reader cluster endpoint, the plugin will retry the initial connection up to `srwConnectRetryTimeoutMs` until it has verified connection to the intended role of the endpoint.
+If it is unable to return a verified initial connection, it will log a message and continue with the normal workflow of the other plugins.
+When connecting with custom endpoints and other non-standard URLs, role verification on the initial connection can also be triggered by providing the expected role through the `verifyOpenedConnectionType` parameter. Set this to `writer` or `reader` accordingly.


Can we consider changing the name from verifyOpenedConnectionType to verifyInitialConnectionType? I think it would be a bit clearer

aaron-congo · 2025-11-14T21:33:26Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+      Connection writerCandidateConn = this.getVerifiedConnection(props, hostSpec, HostRole.WRITER, connectFunc);
+      if (writerCandidateConn == null) {
+        // Can't get writer connection. Continue with a normal workflow.
+        return connectFunc.call();


should we set the initial connection host spec in this case as well or no?

aaron-congo · 2025-11-14T21:34:01Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+          this.getVerifiedConnection(props, hostSpec, HostRole.READER, connectFunc);
+      if (readerCandidateConn == null) {
+        // Can't get a reader connection. Continue with a normal workflow.
+        return connectFunc.call();


same question as above

aaron-congo · 2025-11-14T21:35:04Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+  private final String readEndpoint;
+  private HostSpec readEndpointHostSpec;
+  private HostSpec writeEndpointHostSpec;
+  private final AuroraInitialConnectionStrategyPlugin.VerifyOpenedConnectionType verifyOpenedConnectionType;


Can we move VerifyOpenedConnectionType to its own separate class since it is now shared? The VERIFY_OPENED_CONNECTION_TYPE property can be moved there as well

aaron-congo · 2025-11-14T21:48:40Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+          // No HostSpec provided, still verify role.
+          candidateConn = connectFunc.call();
+        } else {
+          candidateConn = this.pluginService.connect(hostSpec, props, this);


if hostSpec is not null and connectFunc is not null, should we use connectFunc instead of pluginService.connect?

aaron-congo · 2025-11-14T21:59:41Z

wrapper/src/main/java/software/amazon/jdbc/plugin/srw/SimpleReadWriteSplittingPlugin.java

+    try {
+      TimeUnit.MILLISECONDS.sleep(this.connectRetryIntervalMs);
+    } catch (InterruptedException ex) {
+      // ignore


Suggested change

// ignore

Thread.currentThread().interrupt()

sophia-bq force-pushed the feat-srw branch 2 times, most recently from b3b7ada to 367647b Compare November 4, 2025 17:59